Start KYC (Create Sumsub Applicant & Session)

Overview

The Start KYC API initiates the KYC (Know Your Customer) verification flow for an existing application by creating a Sumsub applicant and generating a short-lived session token. This endpoint extracts person details from the application, creates an applicant in Sumsub, and returns the necessary credentials for client-side verification flows.

Authentication

This endpoint requires authentication. See API Authentication for detailed requirements and how to obtain credentials.

Endpoint

POST /api/applications/{applicationID}/kyc/start

Path Parameters

• applicationID (required): The unique application identifier for which to start the KYC flow

Request Body

This API does not require a request body. The endpoint reads the application by applicationID and uses the stored person data.

Response Structure

Interface Definitions

interface StartKYCResponse {
   statusCode: number;
   data: {
      applicantId: string;
      sessionToken: string;
      status: string;
   };
}

interface SumsubApplicantRequest {
   externalUserId: string;
   type: EType.individual;
   fixedInfo: {
      firstName: string;
      lastName: string;
      email: string;
      phone: string;
      dob: string;
   };
}

Success Response

{
   "statusCode": 200,
   "data": {
      "applicantId": "sumsub-applicant-id-123",
      "sessionToken": "eyJhbGciOiJI...",
      "status": "200"
   }
}

Error Response

{
   "statusCode": 400,
   "message": "Validation failed",
   "errors": [
      {
         "field": "firstName",
         "message": "First name is required for KYC applicant creation"
      },
      {
         "field": "email",
         "message": "Email is required for KYC applicant creation"
      }
   ]
}

Field Mapping and Requirements

Required Person Fields

The following fields must be present in the application's person data:

• firstName (string): Required for Sumsub applicant creation
• lastName (string): Required for Sumsub applicant creation
• dob (Date/ISO 8601 string): Date of birth in YYYY-MM-DD format
• email (string): Valid email address
• telephone (string): Phone number, preferably in E.164 format

Field Mapping to Sumsub

Application Field	Sumsub Field	Notes
firstName	fixedInfo.firstName	Direct mapping
lastName	fixedInfo.lastName	Direct mapping
email	fixedInfo.email	Direct mapping
telephone	fixedInfo.phone	Normalized to E.164 format
dob	fixedInfo.dob	Converted to YYYY-MM-DD format

Field Validation Requirements

• All required person fields (firstName, lastName, dob, email, telephone) must be present
• dob must be a valid date in the past
• email must be a valid email format
• telephone should be in valid phone number format
• Application must exist and be accessible

Usage Guidelines

Prerequisites

1. Application Exists: Ensure the application has been created via Submit Application API
2. Person Data: Verify the application contains complete person information
3. TTL Configuration: Optionally configure session TTL via Configure TTL API

Integration Workflow

1. Submit Application: Create application with person details
2. Start KYC: Call this endpoint to initiate verification
3. Client Integration: Use returned sessionToken with Sumsub SDK/widget
4. Monitor Status: Check verification progress via KYC Status API

Session Token Usage

The returned sessionToken is used to:

• Initialize Sumsub verification widget on frontend
• Authenticate client-side SDK requests
• Enable document upload and verification flows

Session Token Security

The session token is short-lived and should be used immediately. Do not store or log session tokens for security reasons.

Integration Tip

Use this endpoint after completing application submission to seamlessly transition users into the verification workflow.

Important

The session token expires based on the configured TTL. Ensure your frontend handles token expiration gracefully.

---